COMMENT ⊗   VALID 00005 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002			  Programming for the Ethernet on WAITS
C00005 00003				     Input and Output
C00007 00004					  MTAPEs
C00010 00005				Miscellaneous information
C00013 ENDMK
C⊗;
		  Programming for the Ethernet on WAITS

The Ethernet on WAITS is implemented as a device driver for device PUP.
Most of the standard WAITS I/O UUOs apply to PUP.  The device PUP has been
made to look like the device IMP as much as possible.

Device PUP can be opened in three different modes.  The mode is determined
from the data mode (this is the first word in the OPEN block).  The three
PUP modes and corresponding data modes are:

   PACKET mode (data mode = 15 [SCOPE DUMP MODE])
   EFTP mode (data mode = 16 [DUMP RECORD MODE] or 13 [IMAGE BINARY MODE])
   BSP mode (data mode = 0, 1, 10, or 17)

It is not possible to change between these modes while an I/O channel is
open.  You may, however, change from dump mode to buffered mode, or vice
versa, with the SETSTS UUO, as long as it does not change the PUP mode.

The I/O UUOs described here may return any of the following error bits in
the I/O status word if they fail.

Name	Interpretation
----	--------------
IOIMPM	Connection not in proper state; the connection either never
	 was opened or is in the process of closing.
IODERR	The console PDP-11 did not accept the Pup (it is probably
	 sick and needs attention).  Only happens on a datagram OUTPUT.
IODTER	Time out; the Pup was not answered within a pre-determined
	 time out interval.  Probably the other host is dead or at
	 least the remote server is down.
IOBKTL	The other host sent us a Pup larger than we can handle in BSP
	 mode.  Since we never allocate it a Pup that large, it is
	 violating protocol.
IODEND	The connection has closed; no more Pups are available for input.
			     Input and Output

PUP data is always transferred in 8-bit bytes.  Each 36-bit PDP-10 word
contains 32 bits of data, starting at the left, so that ILDB and IDPB can
be used to load and store the bytes.  The low order 4 bits should be zero.

I/O is accomplished with the standard UUOs (IN, OUT, INPUT, OUTPUT).  In
dump mode input, there is no way of knowing whether the last word contains
all meaningful data bytes or has some padding null bytes; in buffered mode
input, the byte count in the buffer header will be set correctly.  (There
was a time when the low-order bits of each word indicated padding, but
this is no longer true.)

Before doing any I/O, though, you must open a connection.  This is done
with the MTAPE UUOs discussed below.

A CLOSE UUO (either executed directly or implicitly by a RELEASE) closes
a connection.
				  MTAPEs

Non-I/O portions of the connection are accomplished by the MTAPE UUO.
An MTAPE call is of the form

	MTAPE <channel>,ADR
	...
ADR:	<function number>
	<other data depending on function number>

The success of the operation can be determined by looking at the STATUS
word in the block, generally ADR+1.

The offsets in "block" are:
0	Opcode.  Selects what function to do. (see table below)
1	Status word.  Set as a result of certain conditions. 0 means no error.
2	Local socket.  -1 means let WAITS generate one.
3	Wait flag. -1 = wait for function to complete before continuing.
  NOTE there is a bug in PUPSER because the wait flag isn't handled consistently
4	Byte size.  Checked, but not used.
5	Foreign socket.  Again, -1 means generate one.
6	Foreign host number.  -1 means this is a broadcast packet.

The opcodes are: (the notations	are BSP = BSP mode only, illegal = not allowed,
PKT = packet mode only) note that these opcodes are picked to be similar to the
IMP MTAPE opcodes...
	 0 ESTABLISH CONNECTION
	 1 LISTEN ON A SOCKET
	 2 GET STATUS BITS
	 3 TERMINATE CONNECTION (LIKE CLOSE UUO)
 BSP     4 WAIT FOR CONNECTION
	 5 GET POINTERS TO SYSTEM SYMBOLS
	 6 WAKE UP USER PROCESS FROM I-LEVEL
	 7 GET STATUS BLOCK (USED AFTER LISTEN)
	 10 SKIP IF IMP INPUT
 BSP     11 SEND INR/INS
 illegal 12 TURN ON NCP
 illegal 13 TURN OFF NCP
 BSP     14 TEST AND CLEAR INTERRUPT STATUS
	 15 SET ALLOCATION
	 16 GET ALLOCATION (IN IMPSER)
	 17 SET TIMEOUTS (IN IMPSER)
	 20 GET TIMEOUTS (IN IMPSER)
	 21 GENSYM A SOCKET FOR ICP
 illegal 22 SEND A RESET
 illegal 23 SEND HOST DOWN STATUS MESSAGE
 illegal 24 ATTEMPT TO UNWEDGE AN IMP CONNECTION
 BSP	 25 SEND A MARK
 BSP	 26 RECIEVE A MARK (OR EFTP ABORT CODE)
	 27 GET ROUTING TABLE
 PKT	 30 SET ROUTING TABLE
			Miscellaneous information

Well-known socket numbers:

	Telnet = 1
	Gateway-Info = 2
	FTP = 3
	Misc-Services = 4
	Echo = 5
	BSP-Test = 6
	Mail = 7
	EFTP-Receive = 20
	Ears-Status = 21
	Statistics = 22
	CopyDisk = 25
	Alto-Error-Report = 30
	Printer-Report = 31
	Lisp-Statistics = 33
	Leaf = 43
	Tape = 44
	TeleSwat = 60
	Arpa-Telnet-Gateway = 131
	Grinnell-Server = 104

Some useful Pup types:
 220 = name lookup
 221 = name lookup response
 222 = name lookup error response

Some useful sequences of operations:
-----------------------------------
To request a name -> host number from a name server, use PACKET mode, and
do a "listen" type MTAPE (opcode=1) with the receiving host = -1 (broadcast)
and the receiving socket = 4 (misc. server).
[If you set the wait flag = 0 the UUO will wait to return until the connection
is actually made; this is probably what you want to do.]
Next, send out a PUP on the same channel with the text of the name you want to
look up in the body of the pup and the pup type = 220.  Then use the "skip if
ready" MTAPE (opcode=10) to wait for the answering pup.  If the pup type of
the reply is 221 then the pup body will have all the host/socket numbers
matching in groups of 6 bytes, otherwise the pup body will have the text of
an error message.

Status word bits: (from GETSTS)
40000 = a mark was seen, in BSP mode.  The MTAPE UUO has to be used to
	read the mark.
20000 = EOF.  This happens when the other end closes the connection.